home *** CD-ROM | disk | FTP | other *** search
/ NeXT Enterprise Objects Framework 1.1 / NeXT Enterprise Objects Framework 1.1.iso / NextDeveloper / Headers / foundation / NSLock.h < prev    next >
Encoding:
Text File  |  1995-01-31  |  4.3 KB  |  148 lines
  1. /*    NSLock.h
  2.     Support for locks
  3.       Copyright 1993, 1994, NeXT, Inc.
  4. */
  5.  
  6. #import <foundation/NSObject.h>
  7. #import <foundation/NSDate.h>
  8.  
  9. /***************    Locking protocol        ***************/
  10.  
  11.     /* Locking protocol:
  12.         send "lock" message upon entering critical section
  13.         send "unlock" message to leave critical section
  14.     
  15.     There are classes with different implementations and performance characteristics.  There are example usages preceeding each class definition.
  16.     
  17.     Use NSLock to protect regions of code that can consume long periods of time (disk I/O, heavy computation).
  18.     Use NSConditionLock for those cases where you wish only certain threads to awaken based on some condition you define, or for those cases when you have both short and long critical sections.
  19.     Use NSRecursiveLock to protect regions of code or data that may be accessed by the same thread.  The lock will not block if it is already held by the same thread.  This does not provide mutual exclusion with naive signal handlers...
  20.     
  21.     */
  22.     
  23. @protocol NSLocking
  24.  
  25. - (void)lock;
  26.     // acquire lock (enter critical section)
  27.  
  28. - (void)unlock;
  29.     // release lock (leave critical section)
  30.     // In order to enable clients to only have locks when processes become multithreaded, it must be possible to unlock a lock freshly created (i.e. that has not been locked).
  31.     
  32. @end
  33.  
  34. /***************    NSLock        ***************/
  35.  
  36.     /* NSLock:
  37.     Ordinary, garden variety lock.  Use this if in doubt. 
  38.     Best protection for critical sections that do system calls or heavy computation.  
  39.     Threads will sleep if they cannot immediately acquire the lock
  40.     
  41.     NSLock  *glob = [NSLock new];       // done once!
  42.     [glob lock];
  43.     ... long time of fussing with global data
  44.     [glob unlock];
  45.     
  46.     */
  47.  
  48. @interface NSLock:NSObject <NSLocking> {
  49.     void    *_priv;
  50. }
  51.  
  52. - (BOOL)tryLock;
  53.     /* Returns YES iff lock acquired; returns immediately */
  54.  
  55. - (BOOL)lockBeforeDate:(NSDate *)limit;
  56.     // YES: acquired lock; NO didn't acquire lock
  57.        
  58. @end
  59.  
  60. /***************    NSConditionLock        ***************/
  61.  
  62.     /* NSConditionLock:
  63.     Used to selectively release threads upon conditions
  64.     
  65.     Usage (Producer):
  66.     
  67.     id condLock = [NSConditionLock new];
  68.     [condLock lock];
  69.     ...manipulate global data...
  70.     [condLock unlockWithCondition:NEW_STATE];
  71.     
  72.     Usage (Consumer):
  73.     
  74.     ...The following sleeps until the producer does the unlockWithCondition: such
  75.     that DESIRED_STATE == NEW_STATE.
  76.     [condLock lockWhenCondition:DESIRED_STATE];
  77.     ...manipulate global data if necessary...
  78.     [condLock unlock];
  79.     
  80.     ...OR...
  81.     
  82.     [condLock lockWhenCondition:DESIRED_STATE];
  83.     ...manipulate global data if necessary, then notify other lock users of change of state.
  84.     [condLock unlockWithCondition:NEW_STATE];
  85.     
  86.     The value of 'condition' is user-dependent.
  87.     
  88.     All 4 combinations of {lock,lockWhenCondition} and {unlock,unlockWithCondition} are legal, i.e.,
  89.     
  90.     */
  91.  
  92. @interface NSConditionLock:NSObject <NSLocking> {
  93.     void    *_priv;
  94. }
  95.  
  96. - initWithCondition:(int)condition;
  97.     // init & set condition variable
  98.     
  99. - (int)condition;
  100.  
  101. - (void)lockWhenCondition:(int)condition;
  102.     // acquire lock when conditionVar == condition
  103.     
  104. - (BOOL)lockBeforeDate:(NSDate *)limit;
  105.     // YES: acquired lock; NO didn't acquire lock
  106.        
  107. - (BOOL)lockWhenCondition:(int)condition beforeDate:(NSDate *)limit;
  108.     // YES: acquired lock; NO didn't acquire lock
  109.        
  110. - (BOOL)tryLock;
  111.     /* Returns YES iff lock acquired; returns immediately */
  112.  
  113. - (BOOL)tryLockWhenCondition:(int)condition;
  114.     // acquire lock when conditionVar == condition
  115.     
  116. - (void)unlockWithCondition:(int)condition;
  117.     // release lock and update conditionVar
  118.     
  119. @end
  120.  
  121. /***************    NSRecursiveLock        ***************/
  122.  
  123.     /* NSRecursiveLock:
  124.     used for locks that need to be reacquired by the same thread 
  125.     
  126.     NSRecursiveLock  *glob = [NSRecursiveLock new];       // done once!
  127.     [glob lock];
  128.     ... long time of fussing with global data
  129.     
  130.     [glob lock] from some interior routine
  131.     [glob unlock] 
  132.     
  133.     [glob unlock];
  134.     
  135.     */
  136.     
  137. @interface NSRecursiveLock:NSObject <NSLocking> {
  138.     void    *_priv;
  139. }
  140.  
  141. - (BOOL)tryLock;
  142.     /* Returns YES iff lock acquired; returns immediately */
  143.  
  144. - (BOOL)lockBeforeDate:(NSDate *)limit;
  145.     // YES: acquired lock; NO didn't acquire lock
  146.        
  147. @end
  148.